Node / meshtastic / Meshtastic-Android / files / RELEASE_PROCESS.md

Displaying Rendered • View raw • Download

This guide summarizes the steps for releasing new versions of Meshtastic Android and Desktop. The core flow is automated once a developer triggers the Create or Promote Release workflow; Microsoft Store and winget publishing run as separate workflows (see Desktop Store Publishing).

The entire release process is managed by a single GitHub Action: T383838Create or Promote Release.

• Trigger: To start a new release or promote an existing one, a developer runs the workflow from the GitHub Actions tab.

• Inputs: The workflow requires the following inputs:

1. T383838base_version: The base version number you are releasing (e.g., T3838382.8.0).

2. T383838channel: The release channel you are targeting (T383838internal, T383838closed, T383838open, or T383838production).

3. T383838dry_run: If T383838true, calculates the tag but does not push it or start the release (default: T383838false).

4. T383838no_review_in_flight: Promotions only, and a hard gate. Before promoting, check

Play Console → Publishing overview → Submission activity; if anything reads "In

review", wait. Tick this box to confirm — the workflow fails without it, because

each promotion creates a new Play submission that cancels and restarts any review

already in flight. Internal releases and dry runs are exempt (Play internal testing

skips full review).

• Automation: The workflow handles everything automatically:

• Generates Changelog: Categorizes merged PRs by their labels (per T383838.github/release.yml) into GitHub's auto-generated release notes; a separate automation workflow opens a PR to fold the same notes into T383838CHANGELOG.md.

• Tags & Builds (internal releases): Pushes the incremental tag first — there is no lint/test gate in this workflow, that's the separate PR/CI pipeline — then builds the Android bundle/APK and Desktop installers from that tag; if the build fails, an automatic cleanup job deletes the tag so a retry starts clean. Promotions skip this entirely and retag the already-built artifact (see below).

• Deploys Android: Uploads the build to the correct Google Play track and attaches artifacts (T383838.aab/T383838.apk) to a GitHub Release.

• Deploys Desktop (internal releases): Builds native installers (DMG, MSI, EXE, DEB, RPM, AppImage) and Flatpak sources on a matrix of runners and attaches them to the GitHub Release.

• Changelog: Both the GitHub Release notes and T383838CHANGELOG.md are generated from merged PR labels, not raw commit messages — label PRs correctly (T383838enhancement, T383838bugfix, etc.) to keep them accurate.

• Not part of this workflow: Firmware/hardware/device-links lists and Crowdin translations are kept current by a separate hourly workflow, T383838scheduled-updates.yml ("Scheduled Updates (Firmware, Hardware, Translations)"), which opens its own PR rather than committing directly — it never runs as part of a release. T383838VERSION_NAME_BASE in T383838config.properties is likewise never written by automation: a maintainer bumps it by hand in an ordinary PR (e.g. "chore: bump VERSIONNAMEBASE to 2.8.2 (#6820)") before starting a release for a new base version, paired with a matching T383838<release> entry in T383838desktopApp/packaging/linux/org.meshtastic.MeshtasticDesktop.metainfo.xml — a T383838pull-request.yml check fails the PR if that entry is missing. T383838Create or Promote Release only reads T383838VERSION_NAME_BASE/T383838VERSION_CODE_OFFSET from T383838config.properties to compute the build's version name/code.

1. Navigate to the Actions tab in the GitHub repository.

2. Select the T383838Create or Promote Release workflow.

3. Click the "Run workflow" dropdown.

4. Enter the T383838base_version (e.g., T3838382.8.0).

5. Select the T383838internal channel.

6. Click "Run workflow". (Tip: enable T383838dry_run first to preview the tag that would be created without pushing anything.)

The workflow will:

1. Tag the current commit on the branch with an incremental internal tag (e.g., T383838v2.8.0-internal.1) — no new commit is created; it tags whatever is already at T383838HEAD.

2. Build & Deploy the built Android artifact to the Play Store Internal track.

3. Build Desktop native installers and Flatpak sources on macOS, Windows, and Linux runners.

4. Publish a draft pre-release on GitHub with all artifacts attached. It stays a draft until

the first promotion (closed/open/production), at which point T383838promote.yml un-drafts the

same release object (retagging it to the new channel's tag) rather than creating a new one.

Once an internal build has been verified, you can promote it to a wider audience.

1. Run the T383838Create or Promote Release workflow again with the same T383838base_version.

2. Select the next channel in the sequence (e.g., T383838closed, then T383838open).

3. The workflow will create a new incremental tag for that channel (e.g., T383838v2.8.0-closed.1) and create a published pre-release on GitHub.

After testing is complete on all pre-release channels, you can create the final public release.

1. Run the T383838Create or Promote Release workflow one last time.

2. Use the same T383838base_version.

3. Select the T383838production channel.

4. The workflow will create a clean version tag (e.g., T383838v2.8.0) and create a published, stable (non-prerelease) release on GitHub.

1. Verify Android: Check the Google Play Console to ensure the build is available on the correct track.

2. Verify Desktop: Download and smoke-test at least one installer (DMG, MSI, or AppImage) from the GitHub Release.

3. Verify the desktop store submissions (production only — see below): the Microsoft Store

submission in Partner Center, and the pull request opened against T383838microsoft/winget-pkgs.

4. Merge: If a T383838release/* branch was used for stabilization (CI runs the same PR checks

against PRs targeting T383838release/** as it does for T383838main), merge it back into T383838main now

that production has shipped.

Publishing a production release also fires two workflows, both keyed on the GitHub

T383838release: released event:

Neither fires for drafts or pre-releases, so internal/closed/open promotions are ignored.

T383838released also fires when T383838promote.yml flips an existing pre-release to a full release — but

because that edit uses the workflow's own T383838GITHUB_TOKEN, and events caused by T383838GITHUB_TOKEN

never start workflow runs, T383838promote.yml dispatches both workflows explicitly as well. Each also

accepts a manual T383838workflow_dispatch with a T383838tag, which is the retry path if either fails.

Desktop native installers are built automatically as part of every T383838internal release. There is no separate promotion flow for Desktop — installers are built once during the T383838internal release and attached to the GitHub Release alongside Android artifacts; promotions to later channels reuse them.

macOS builds are signed and notarized when the following CI secrets are configured: